home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 096 / dirnly11.arc / DIRONLY.DOC < prev    next >
Text File  |  1986-11-18  |  10KB  |  227 lines
  1.   DIRONLY version 1.1 - (c) 1986 by Ken Goosens
  2.   11-17-86                          10201 Grosvenor, #1614
  3.                                     Rockville, MARYLAND, USA
  4.  
  5.   Ken Goosens can be reached on his bulletin board at 202-537-7475
  6.   or 202-537-7945.
  7.  
  8.   A complete set of files for this program includes:
  9.  
  10.             DIRONLY.DOC - this file
  11.             DIRONLY.EXE - Executable code
  12.             DIRONLY.BAS - source code
  13.  
  14.  
  15.   UPDATE HISTORY
  16.  
  17.   Update 1.1.  11-17-86.  Enhanced to exclude comment lines
  18.   from list of files.  Was erroneously interpreting lines with
  19.   commentary as directory entries.
  20.  
  21.   First released.  11-14-86.
  22.  
  23.  
  24.   LIMITED LICENSE
  25.  
  26.   The author reserves all rights to any revenue from the use or distribution
  27.   of DIRONLY.  This means that if the use of DIRONLY helps you make money,
  28.   the author expects some form payment for its use.  The payment is
  29.   negotiable and may be an exchange of goods or services as well as money.
  30.   If you want to use DIRONLY in support of a business that generates revenue,
  31.   you must obtain a license from the author.  The author grants individuals
  32.   a free license to use DIRONLY only in support of a free, public service.
  33.   This is true not only for DIRONLY, but for any use of the source code.
  34.   Corporate use or redistribution requires a site license.  Bulletin boards
  35.   and non-profit computer organizations can distribute copies, but distribution
  36.   with a commercial product requires a license.
  37.  
  38.   Can I freely use DIRONLY if
  39.  
  40.      o  I run a commercial bulletin board where I charge an annual fee, say
  41.         $25?
  42.  
  43.         Answer:  No.  But you can make DIRONLY available for downloading.
  44.    
  45.      o  I run a commercial board but offer a free public board in addition?
  46.  
  47.         Answer:  Yes, the free public service is enough.
  48.  
  49.      o  I run a government bulletin board, charging users only enough to
  50.         cover costs?
  51.  
  52.         Answer:  No, the board is not free and generates revenue.  Count
  53.         the use of DIRONLY as a part of your expenses.
  54.  
  55.   Can I freely distribute DIRONLY if
  56.  
  57.      o  I give it away for free to people who buy my bulletin board
  58.         software?
  59.  
  60.         Answer:  No, no more than you can give IBM's DOS away.  Whatever
  61.         enhances the value of your commercial product deserves remuneration.
  62.  
  63.      o  I charge people for the cost of a diskette and a small service fee?
  64.  
  65.         Answer:  It depends.  Not if there are profits from the sale which
  66.         go into salaries or commissions.  But yes if the sales exclusively
  67.         support a non-profit service organization, like a computer user group.
  68.   
  69.  
  70.   WHAT DOES DIRONLY DO?
  71.  
  72.   DIRONLY is a utility which checks to see whether the files in
  73.   lists of files really do exist and if they are in the file directory
  74.   only and not present, outputs the names of the missing files.
  75.  
  76.   This is most useful for bulletin board systems that maintain lists
  77.   of files that can be downloaded.  You can run DIRONLY to validate
  78.   your lists.
  79.  
  80.  
  81.   ASSUMPTIONS THAT DIRONLY MAKES
  82.  
  83.   DIRONLY should work properly with many bulletin board systems,
  84.   including RBBS and PC-Board.  The only assumptions it makes are
  85.  
  86.       (1)  File names are stored as the first word in a line, begin
  87.            in column 1, terminate with a space, and have at most 
  88.            12 characters.
  89.  
  90.       (2)  Each line with a file name terminates with a carriage-return
  91.            line-feed.
  92.  
  93.       (3)  Unless you specify a minimum line size below 26, DIRONLY
  94.            assumes that lines with file name entries have at least 29
  95.            characters and have a dash (-) in columns 26 and 29 (as a date
  96.            divider).
  97.  
  98.            Lines not satisfying these requirements are assumed to be
  99.            commentary lines in a directory rather than directory entries.
  100.  
  101.       (4)  There are not more than 100 directories to search.
  102.  
  103.   Additional text can occur after the file name as long as there is a
  104.   space between the file name and the additional text.
  105.  
  106.   When a file name is not found, its entire line and not just the name is
  107.   written out the the file of missing files.
  108.  
  109.  
  110.   A QUICK START
  111.  
  112.   You run a bulletin board system.  You keep lists of downloadable files
  113.   in the following files:  UPLOADS.DIR, ALPHA.DIR, COMM.DIR.  You want
  114.   to make sure that all of the files listed in these three files really
  115.   are available to callers for downloading.  You allow downloading from
  116.   the following subdirectories:   C:\UP, D:\OLD, E:\OLD.   There are 3
  117.   steps you need to take to use DIRONLY:
  118.  
  119.      o   Create a file called FILEDIRS which has your list of directory
  120.          files in it, one to a line.  The following 3 lines would be in
  121.          it:
  122.  
  123.                               UPLOADS.DIR
  124.                               ALPHA.DIR
  125.                               COMM.DIR
  126.  
  127.          You can also include and drive/path in front of the file name
  128.          if there files are not on the default direcory.
  129.  
  130.      o   Create a file called DRVDIRS which has the places to search for
  131.          files in it, one to a line.  The following 3 lines would be in
  132.          it:
  133.  
  134.                               C:\UP
  135.                               D:\OLD
  136.                               E:\OLD
  137.  
  138.          A tip:  performance will be improved if you list the directories
  139.          in the most likely order files will be found.
  140.  
  141.      o   Invoke DIRONLY.  It will ask you to confirm that the minimum
  142.          line length for directory entries is 29, the file of
  143.          directories in FILEDIRS, the file of drive/paths to search is
  144.          DRVDIRS, and you want the missing files listed in MISSING.FIL.
  145.          Press RETURN and you will get a status as DIRONLY searches for
  146.          any missing files.
  147.  
  148.   What you do with the listing of missing files is up to you.  Most people
  149.   print it and then either restore the missing file or edit out the entry
  150.   from the directory file.
  151.  
  152.  
  153.                           
  154.   WHAT'S DIFFERENT ABOUT DIRONLY?
  155.  
  156.   There are other utilities that do the same thing.  The main difference
  157.   in DIRONLY is that
  158.  
  159.      o  there is NO EFFECTIVE LIMIT on the size of the directories or
  160.         the number of files it will check.
  161.  
  162.   Hence DIRONLY will work properly ON VERY LARGE SYSTEMS of any size.
  163.   DIRONLY has no effective limit because it does not read the directories
  164.   into memory but simply uses DOS calls to check whether a file exists. 
  165.  
  166.   BUT DOESN'T THIS MEAN THAT DIRONLY IS DOG SLOW because of the many disk
  167.   accesses when the number of files on disk is large?  YES and NO.  DIRONLY
  168.   is as fast as DOS - which starts to get slow where the number of files in
  169.   directories gets to be over 512.   Yes - when there are many large
  170.   subdirectories to search.  A program that reads the directories into
  171.   memory, sorts them alphabetically, and does a binary search will outperform
  172.   DIRONLY when the number of files gets large - say 1000-3000.  BUT
  173.   performance is not as bad as you might fear because DIRONLY uses adaptive
  174.   search routines to decide where to look and learns from experience!
  175.  
  176.   DIRONLY performs two adaptive adjustments in its searches.  First, it keeps
  177.   an evolving list of what order to search the drive/paths for every
  178.   drive/path.  And second, it decides which search list to use based on where
  179.   it last found a file.  Most directory lists are highly clustered - files
  180.   tend to be stored together - and DIRONLY will perform very well when this
  181.   occurs.
  182.  
  183.   Searching for 106 files in two file directories across two drive directories
  184.   with 39 and 336 files in them, when 3 files were missing, took approximately
  185.   27 seconds.  Checking 8200 entries on a large networked system look about
  186.   2 hours.
  187.  
  188.  
  189.   HOW TO RUN DIRONLY
  190.  
  191.   DIRONLY works by invoking it with arguments.  The format is
  192.  
  193.           DIRONLY [/M=x] <file dirs> <drive/path dirs> <output>
  194.  
  195.   where
  196.           /M=x = Minimum size of a valid line (exclude shorter)
  197.           <file dirs> = file of directory files (lists of files)
  198.           <drive/path dirs> = file of drive/paths to search
  199.           <output> = list of files found to be missing
  200.  
  201.   DIRONLY will display a copyright and a page of documentation, and  
  202.   ask you to <Q>uit or <R>un with the specified setup.
  203.  
  204.   The optional minimum size parameter can be used to control whether
  205.   DIRONLY will exclude lines because they lack a date.  Many sysops
  206.   include text commentary lines inside directory files which should
  207.   be excluded rather than interpreted as a directory entry.  Normal
  208.   directory entires have a date in the form MM-DD-YY beginning in
  209.   column 24.  DIRONLY will look in columns 26 and 29 for a dash
  210.   and exclude the line as a non-directory entry if there is no dash.
  211.   If you want DIRONLY not to use the date exclusion test, set the
  212.   minimum length below 26 (the date field requires the line to have at
  213.   least 29 characters).  This might be useful if you have only a
  214.   list of only file names you want to check.  DIRONLY will still
  215.   exclude lines below this minimum length, so if you want no exclusion
  216.   at all, set the minimum to be 0.
  217.  
  218.  
  219.   RECOMPILING
  220.  
  221.   DIRONLY is written in QuickBasic and the source is enclosed in the
  222.   hopes that people will correct bugs and add enhancements which they
  223.   will share.  If you want to share enhancments, please send them to
  224.   the author rather than distributing them independently.  DIRONLY uses an
  225.   assembler routine from the ADVANCED BASIC library distributed by TOM
  226.   HANLIN to determine whether a file exists.
  227.